<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
 <META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 0.9.21">
 <TITLE>Netfilter Extensions HOWTO: Patch-O-Matic</TITLE>
 <LINK HREF="netfilter-extensions-HOWTO-3.html" REL=next>
 <LINK HREF="netfilter-extensions-HOWTO-1.html" REL=previous>
 <LINK HREF="netfilter-extensions-HOWTO.html#toc2" REL=contents>
</HEAD>
<BODY>
<A HREF="netfilter-extensions-HOWTO-3.html">Next</A>
<A HREF="netfilter-extensions-HOWTO-1.html">Previous</A>
<A HREF="netfilter-extensions-HOWTO.html#toc2">Contents</A>
<HR>
<H2><A NAME="s2">2.</A> <A HREF="netfilter-extensions-HOWTO.html#toc2">Patch-O-Matic</A></H2>

<H2><A NAME="ss2.1">2.1</A> <A HREF="netfilter-extensions-HOWTO.html#toc2.1">What is Patch-O-Matic ?</A>
</H2>

<P>Netfilter developers distribute a set of patches that they package
so that it can be used by their `patch-o-matic' (or `p-o-m') system.
p-o-m is a script that guides you through the process of choosing/selecting
the patches you want to apply, and automatically patch the kernel for you.</P>

<P>First, you should get the latest CVS tree, to be sure that you are using the
latest extensions. To do so, perform :</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
# cvs -d :pserver:cvs@pserver.netfilter.org:/cvspublic login

(When it asks you for a password type `cvs').

# cvs -d :pserver:cvs@pserver.netfilter.org:/cvspublic co netfilter/userspace netfilter/patch-o-matic
</PRE>
</CODE></BLOCKQUOTE>
</P>

<P>This will create the toplevel directory `netfilter/', and will
check out all the files inside for you :</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
# ls -l netfilter/
total 3
drwxr-xr-x    2 root     root          160 Nov  7 14:48 CVS/
drwxr-xr-x   13 root     root          488 Nov  7 14:54 patch-o-matic/
drwxr-xr-x    9 root     root          864 Nov  7 14:48 userspace/
</PRE>
</CODE></BLOCKQUOTE>
</P>

<P>Make sure your kernel source is ready in `/usr/src/linux/'.
If for whatever reason the kernel you want to patch is not
in `/usr/src/linux/' then you can make the variable KERNEL_DIR
point to the patch where your kernel is :</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
# export KERNEL_DIR=/the/path/linux
</PRE>
</CODE></BLOCKQUOTE>
</P>

<P>Make sure the dependencies are made already. If unsure :</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
# cd /usr/src/linux/
# make dep
</PRE>
</CODE></BLOCKQUOTE>
</P>

<P>Then you can go back to the netfilter directory, in the `patch-o-matic/' directory.
You can now invoke p-o-m.</P>

<H2><A NAME="ss2.2">2.2</A> <A HREF="netfilter-extensions-HOWTO.html#toc2.2">Running Patch-O-Matic</A>
</H2>

<P>While in the `patch-o-matic/' directory, let's run p-o-m :</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
# ./runme extra

Welcome to Rusty's Patch-o-matic!

Each patch is a new feature: many have minimal impact, some do not.
Almost every one has bugs, so I don't recommend applying them all!
-------------------------------------------------------

Already applied: 2.4.1 2.4.4
Testing... name_of_the_patch NOT APPLIED ( 2 missing files)
The name_of_the_patch patch:
   Here usually is the help text describing what
   the patch is for, what you can expect from it,
   and what you should not expect from it.
Do you want to apply this patch [N/y/t/f/q/?]
</PRE>
</CODE></BLOCKQUOTE>
</P>

<P>p-o-m will go through most of the patches. If they are already applied,
you will see so on the `Already applied:' first line. If they are not applied
yet, it will display the name of the patch with some explanations.
p-o-m will tell you what is going on : `NOT APPLIED ( n missing files)' simply means
the patch has not been applied yet, whereas `NOT APPLIED ( n rejects out of n hunks)'
generally means that :
<OL>
<LI>Either the patch cannot be applied cleanly...</LI>
<LI>...Or the patch has already been included in the kernel you are trying to patch.</LI>
</OL>
</P>

<P>Finally it will prompt you to decide whether or not to patch it. </P>
<P>
<UL>
<LI>Simply press enter if you do not want to apply it.</LI>
<LI>Type `y' if you want p-o-m to test the patch and apply it,
if the attempt fail then it will tell you so and prompt you again for confirmation.
If not, the patch will be applied, and you will see the name of the patch
on the `Already Applied' line.</LI>
<LI>Type `t' if you just want to test if the patch would apply normally.</LI>
<LI>Type `f' if you
want to force p-o-m to apply the patch.</LI>
<LI>Finally type `q' if you want to quit p-o-m.</LI>
</UL>
</P>

<P>A rule of thumb is to read carefully the little explanation text of each patch
before actually applying it. As there are currently a LOT of official patches for patch-o-matic
(and probably more unofficial ones), it is not recommended to apply them all !
You should really consider applying only the ones you need, even if it means recompiling
netfilter when you need more patches later on.</P>

<P>Patch-o-matic in fact, is mainly the `runme' shell script. If you run it without arguments, it will
display its help message :</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
Usage: ./runme [--batch] [--reverse] [--exclude suite/patch-file ...] suite|suite/patch-file

  --batch       batch mode, automatically applying patches
  --reverse     back out the selected patches
  --exclude     excludes the named patches
</PRE>
</CODE></BLOCKQUOTE>
</P>

<P>The patches are contained in `patch-o-matic/pending/', `patch-o-matic/base', etc.. Here, `pending' and `base'
are two suite names. ls the `patch-o-matic' directory to see all the suites. Example of `runme' commands :</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
./runme --batch pending
./runme --batch userspace/ipt_REJECT-fake-source.patch
</PRE>
</CODE></BLOCKQUOTE>
</P>

<P>The first command will attempt to apply all the patches from submitted suite,
then the pending suite (we explain further why two suites). The second command
will only apply the patch `ipt_REJECT-fake-source.patch' from the userspace suite.</P>

<P>The most relevant patches `suites' or repositories are (in their order or application) :
<UL>
<LI>submitted</LI>
<LI>pending</LI>
<LI>base</LI>
<LI>extra</LI>
<LI>userspace</LI>
</UL>
</P>

<P>When you instruct `./runme' to apply patches from the `extra/' patch repository it will first
present you with the patches from the `submitted/', `pending/', and `base/' directories.
Each suite, maintain a file named `SUITE' that instruct p-o-m of the order in which
it should attempt to apply the patches. For example, what I explained above is written
in the `userspace/' repository's `SUITE' file :</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
# cat userspace/SUITE
submitted pending base extra userspace
</PRE>
</CODE></BLOCKQUOTE>
</P>

<H2><A NAME="ss2.3">2.3</A> <A HREF="netfilter-extensions-HOWTO.html#toc2.3">So what's next ?</A>
</H2>

<P>Once you have applied all the patches you wished to apply, the next step is recompile
your kernel and install it. This HOWTO will not explain how to do this. Instead, you
can read the 
<A HREF="http://www.linuxdoc.org/HOWTO/Kernel-HOWTO.html">Linux Kernel HOWTO</A>.</P>

<P>While configuring your kernel, you will see new options in
``Networking Options -&gt; Netfilter Configuration''. Choose the options
you need, recompile &amp; install your new kernel.</P>

<P>Once your new kernel is installed, you can go ahead and compile and install the ``iptables''
package, from the `userspace/' directory as follows :</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
# make all install
</PRE>
</CODE></BLOCKQUOTE>
</P>

<P>That's it ! Your new shiny iptables package is installed ! Now it's time
to use these brand new functionalities.</P>

<HR>
<A HREF="netfilter-extensions-HOWTO-3.html">Next</A>
<A HREF="netfilter-extensions-HOWTO-1.html">Previous</A>
<A HREF="netfilter-extensions-HOWTO.html#toc2">Contents</A>
</BODY>
</HTML>
